/**
 * @file base_file_parser.h
 * @brief 基准文件解析模块头文件
 */

#ifndef BASE_FILE_PARSER_H
#define BASE_FILE_PARSER_H

#include <stdint.h>

// Feature flags for base file
#define FEATURE_PITCH       0x0001  // Pitch feature
#define FEATURE_TIMBRE      0x0002  // Timbre feature 
#define FEATURE_RHYTHM      0x0004  // Rhythm feature
#define FEATURE_ENERGY      0x0008  // Energy feature
#define FEATURE_BRIGHTNESS  0x0010  // Brightness feature
#define FEATURE_SPECTRUM    0x0020  // Spectrum data

// Base file header structure definition
#pragma pack(push, 1)
typedef struct {
    char magic[4];            // Magic, fixed as "VBAS"
    uint16_t version;         // File version number
    char song_id[64];         // Song unique identifier
    uint32_t total_frames;    // Total frame count
    uint32_t sample_rate;     // Voice processing sample rate
    uint16_t frame_size;      // Processing frame size (samples)
    uint16_t hop_size;        // Hop size (samples)
    uint16_t precision;       // Data precision and reserved bits (low 8 bits=precision, high 8 bits=reserved)
    uint16_t features_flag;   // Feature presence flags (bitmap)
    uint16_t checksum;        // File checksum
    uint32_t num_sentences;   // 歌词句子总数 (自 v1.1 增加)
    uint8_t reserved[36];     // Reserved fields for future expansion
} BaseFileHeader;  // Total size: 128 bytes
#pragma pack(pop)

// 基准文件帧数据结构 - 确保内存布局与文件布局一致
#pragma pack(push, 1)
typedef struct {
    int frame_index;             // 帧序号
    float vad_value;             // 当前帧VAD值（语音活动检测），范围0.0-1.0
    signed char spectrum[256];          // 当前帧频谱显示数据（256字节）
    float energy;                // 当前帧能量值
    float pitch;                 // 音准值
    float rhythm;                // 节奏值
    float brightness;            // 明亮度值
    float timbre;                // 音色值
} BaseFrameData;
#pragma pack(pop)

/**
 * @brief 计算校验和
 * 
 * @param data 数据指针
 * @param size 数据大小
 * @return uint16_t 校验和
 */
uint16_t calculate_checksum(const void* data, size_t size);

/**
 * @brief 验证文件校验和
 * 
 * @param header 文件头指针
 * @param data 数据指针
 * @param data_size 数据大小
 * @return int 校验成功返回1，失败返回0
 */
int verify_file_checksum(const BaseFileHeader* header, const void* data, size_t data_size);

/**
 * @brief 打印基准文件头信息
 * 
 * @param header 文件头指针
 */
void print_base_file_header(const BaseFileHeader* header);

/**
 * @brief 验证基准文件头
 * 
 * @param header 文件头指针
 * @param expected_sample_rate 期望的采样率，0表示不检查
 * @param expected_frame_size 期望的帧大小（半帧大小），0表示不检查
 * @return int 成功返回0，失败返回错误码
 */
int validate_base_file_header(const BaseFileHeader* header, int expected_sample_rate, int expected_frame_size);

/**
 * @brief 从文件路径加载基准文件
 *
 * @param file_path 文件路径
 * @param header_out 输出文件头
 * @param data_out 输出数据指针（需要调用方free）
 * @param data_size_out 输出数据大小
 * @return int 成功返回0，失败返回错误码
 */

int load_base_file(const char* file_path, BaseFileHeader* header_out, void** data_out, size_t* data_size_out);

/**
 * @brief 从内存数据加载基准文件
 *
 * @param data_buffer 文件数据缓冲区
 * @param buffer_size 缓冲区大小
 * @param header_out 输出文件头
 * @param data_out 输出数据指针（需要调用方free）
 * @param data_size_out 输出数据大小
 * @return int 成功返回0，失败返回错误码
 */
int load_base_file_data(const void* data_buffer, size_t buffer_size, BaseFileHeader* header_out, void** data_out, size_t* data_size_out);

#endif /* BASE_FILE_PARSER_H */ 